home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1993 September / September 93.iso / Archives / Utilities / Text / TCXdiff 1.0b1 / TCXdiff Readme.txt < prev   
Text File  |  1993-09-29  |  11KB  |  209 lines
  1. TCXdiff 1.0b1
  2. =============
  3.  
  4. [ TCXdiff requires System 7.x.                                  ]
  5. [ TCXdiff is © Tat C. Wan, 1993.                                ]
  6. [ Portions © Symantec. Xdiff code modified from NCSA's sources. ]
  7. [ This program is freeware.                                     ]
  8.  
  9. This file is best viewed using a monospaced font (like Monaco or Courier). 
  10.  
  11. 1) What is it? 
  12.  
  13. TCXdiff is a text file comparison utility which generates a difference (diff)
  14. file for a given source file. The diff file can be used to update an older
  15. version of the source file stored on another computer (normally, a Unix
  16. machine). By transferring the much shorter diff file instead of the entire
  17. source file, significant upload time can be saved. This is especially useful
  18. for people who connect to Unix hosts using slow dial-up modems. Although the 
  19. primary focus of TCXdiff is for programmers who need to synchronize their 
  20. program files between their personal computer and a Unix host, it can be used
  21. to update any other text file as well.
  22.  
  23. TCXdiff is based on the freeware program Xdiff written in August 1989 at the
  24. National Center for Supercomputing Applications (NCSA). You can obtain Xdiff
  25. via anonymous ftp from ftp.ncsa.uiuc.edu. The Xdiff package is needed in 
  26. addition to TCXdiff since TCXdiff DOES NOT perform the updating per se, but 
  27. relies on  xfix (part of the Xdiff package) to perform that task. Xfix was 
  28. written  primarily for Unix hosts, I have not tried to compile it on other
  29. platforms.
  30.  
  31. TCXdiff is functionally equivalent to Xdiff. However, it adds the ability to
  32. specify default folders and filenames (useful for batch processing), as well 
  33. as drag-and-drop file processing capabilities.
  34.  
  35. 2) How does it work? 
  36.  
  37. In order to maintain and update text files stored on Unix machines with edited
  38. versions created on a Macintosh, the following steps are needed:
  39.  
  40. First, a control file is created, which is typically the first version of the
  41. file. This control file MUST exist on both the Macintosh and the Unix host.
  42. Then, as changes are made to the text file (called the source file), these
  43. changes can be tracked and uploaded to the Unix host by means of difference
  44. (diff) files that is generated by TCXdiff. The xfix program then takes the diff
  45. file and the control file (residing on the Unix host) and creates an up-to-date
  46. version of the source file (let's call it the source* file).
  47.  
  48. This can be illustrated in the following diagram:
  49.  
  50.               >>        [source file]       [control file]
  51.               >>              |                    |
  52.               >>              +---------+----------+
  53.               >>                        |
  54.     Macintosh >>                        v
  55.               >>                   > TCXdiff <
  56.               >>                        |
  57.               >>                        v
  58.               >>                   [diff file]
  59.                                         |
  60.                                         |   (transmission: modem, 
  61.                                         /    serial link, etc.)
  62.                                +-------/
  63.               >>               |            [control file]  (must be identical
  64.               >>               |                   |         to control file
  65.               >>               +---------+---------+         on Mac)
  66.               >>                         |
  67.       Unix    >>                         v
  68.       host    >>                     > xfix <
  69.               >>                         |
  70.               >>                         v
  71.               >>                   [source* file]   (updated version of source
  72.               >>                                     file)
  73.  
  74. The control and diff files usually have the same name as the source file, with
  75. the addition of a prefix. Let the source file be "mySource.p". The control file
  76. will have a default prefix of "c." (i.e. "c.mySource.p"), which is what xfix
  77. expects. Diff files can have any prefix, I'm using "X." as the default (i.e.
  78. "X.mySource.p"). I have included the ability to specify different prefixes for
  79. the control and diff files. What I do typically is to have all my source files
  80. in its own folder (e.g. mySource Folder) and the control files in another
  81. folder (e.g. myControl Folder). When a sufficient number of revisions to the 
  82. source file have been made, I generate the latest diff file, upload it to the
  83. Unix host, and generate the updated source file. Then, I update the control 
  84. file on the Macintosh by replacing it with the latest version in mySource 
  85. Folder (by means of the "Make/Update Control File" command in TCXdiff), as well
  86. as update the control file on the Unix host by copying the updated version of
  87. the source file over the existing control file (you'll have to do this step 
  88. yourself, sorry). In this way, the size of the diff file does not continually
  89. increase with each revision.
  90.  
  91. If the version of the control file on the Unix host is different from the one
  92. on the Mac, xfix will complain about a checksum error and will not generate
  93. the updated source file (it generates an EMPTY updated source file). If that
  94. happens, you should upload the new source file and update the respective
  95. control files on the Unix host and the Mac for future use instead.
  96.  
  97. 3) Commands in TCXdiff
  98.  
  99. Almost all commands in TCXdiff can be accessed via the Settings dialog as well
  100. as through menu items. Here's a brief explanation of what they mean:
  101.  
  102. File Menu:
  103.   TCXdiff Settings...           Opens the TCXdiff Settings dialog to start 
  104.                                   processing
  105.   Close                         Close the TCXdiff Settings dialog
  106.   Save Prefs                    Save the current preferences (if changed)
  107.   Always Save Prefs             Does not prompt user to save changed prefs
  108.                                  (automatically save any changed prefs)
  109.   Always Overwrite Cntl File    Does not prompt user if control file should be
  110.                                   overwritten (automatically overwrite)
  111.   Quit                          Exactly what it means
  112.  
  113. Edit Menu:
  114.   (Not used in TCXdiff)
  115.  
  116. Xdiff Menu:
  117.   Source File...                Specify the source file
  118.   Control File...               Specify the control file
  119.   Diff file...                  Specify the diff file
  120.   Make/Update Cntl File         Make control file for specified source file if it
  121.                                   is not specified or does not exist, otherwise
  122.                                   update control file
  123.   Generate Diff File            Generate the diff file
  124.   
  125. Xdiff Settings:
  126.   Use Default Cntl File         Search for control files in the default control
  127.                                   folder, using the control prefix and source
  128.                                   filename as the name of the control file
  129.   Use Default Diff File         Store diff files in default diff folder
  130.   Set Cntl Prefix...            Specify the control prefix for locating default
  131.                                   control filenames
  132.   Set Diff Prefix...            Specify the diff prefix for generating default
  133.                                   diff filenames
  134.   Set Default Cntl Folder...    Specify the default folder for locating control
  135.                                   files
  136.   Set Default Diff Folder...    Specify the default folder for locating diff
  137.                                   files
  138.  
  139. You can only make control files if the source file has been specified. If the
  140. "Use Default Cntl File" checkbox is checked, then the control filename and
  141. folder is generated automatically. If the "Always Overwrite Cntl File" menu
  142. item is checked, then you are not prompted if the control file should be 
  143. overwritten when you make or update the Control file. You cannot overwrite
  144. the source file that is currently active.
  145.  
  146. The diff file is always overwritten automatically (unless it happens to be
  147. either the source or control file, in which case the command will abort).
  148. It is therefore suggested to always define a file prefix for diff files,
  149. so as not to overwrite other files accidentally. 
  150.  
  151. You can only process a source file (i.e. generate the diff file) if all three
  152. types of files have been specified. You can also process a source file via
  153. drag-and-drop. If either the control file or diff files were not specified as
  154. "Use Default" or if the control file was not found, you will be prompted to
  155. locate the relevant files. It is recommended that "Use Default" be checked 
  156. (after the respective parameters have been set up correctly, of course) to 
  157. automate the drag-and-drop generation of diff files.
  158.  
  159. The status windows will indicate the pathname of the file if it has been
  160. specified correctly (either automatically or manually via the "Source File",
  161. "Control File" or "Diff File" buttons/menu items).
  162.  
  163. Tidbit: I've included a TMPL resource in the application, which allows you
  164. to edit some of the default preferences in TCXdiff's PREF resource (generated
  165. if a valid preference file was not found). This assumes that you know how to 
  166. use Resedit, and do work on a copy of the program, etc.
  167.  
  168. 4) Acknowledgements
  169.  
  170. This is my first attempt at releasing a Macintosh program :0). Since I have
  171. limited access to different machines, this was only tested on a IIsi running
  172. System 7.01•. I wrote TCXdiff in order to learn how to use the Think Class
  173. Library better, as well as take care of some of the shortcomings of Xdiff.
  174. Besides, Xdiff was not compatible with ApplWindows, a really nice freeware
  175. process manager. I decided that I liked ApplWindows too much to give it up, so
  176. TCXdiff was born.
  177.  
  178. Thanks to Jon Wätte for his Mac Programming FAQ, Jamie McCarthy for the
  179. CPrefsFile code, Andrew Gilmartin for the TCL archive, and  the folks on the
  180. Internet for their valuable help. I'd like to dedicate this modest effort to 
  181. all those people who'd written some great freeware/shareware programs for the
  182. Macintosh.
  183.  
  184. 5) Legalese
  185.  
  186. TCXdiff is free, but it is not in the public domain. I do not make any
  187. warrantees as to its useability, nor am I responsible for any damages arising
  188. from its use. It may be freely distributed by and for any non-commercial or
  189. non-profit venture. You may not charge for TCXdiff above and beyond any routine
  190. connect-time and downloading charges.
  191.  
  192. 6) Future plans
  193.  
  194. Porting xfix to the Macintosh: it should not be too difficult, but getting
  195. TCXdiff off the ground has taken longer than I'd anticipated already. You're
  196. welcome to send suggestions, comments, bug reports to me at:
  197.  
  198.     tcwan@umiami.miami.edu
  199.  
  200. Thanks.
  201. t.c. 9/29/93
  202.  
  203. --
  204. Revision History
  205. ================
  206.  
  207. 9/29/93        Version 1.0b1        First Public Release.
  208.  
  209.